atspi: Add some docs

Add a comment that explains a few of the more subtle
points of the Atspi context tree contstruction.

diff --git a/gtk/a11y/gtkatspicontext.c b/gtk/a11y/gtkatspicontext.c
index 40c655f04a6a4114c888c777bdc1a91bf679494d..36f463686272f5c6593017812fccbe3daf1d9071 100644 (file)
--- a/gtk/a11y/gtkatspicontext.c
+++ b/gtk/a11y/gtkatspicontext.c
@@ -59,6 +59,27 @@
 # include <gdk/x11/gdkx11property.h>
 #endif
 
+/* We create a GtkAtSpiContext object for (almost) every widget.
+ *
+ * Each context implements a number of Atspi interfaces on a D-Bus
+ * object. The context objects are connected into a tree by the
+ * Parent property and GetChildAtIndex method of the Accessible
+ * interface.
+ *
+ * The tree is an almost perfect mirror image of the widget tree,
+ * with a few notable exceptions:
+ *
+ * - We don't create contexts for the GtkText widgets inside
+ *   entry wrappers, since the Text functionality is represented
+ *   on the entry contexts.
+ *
+ * - We insert non-widget backed context objects for each page
+ *   of a stack. The main purpose of these extra context is to
+ *   hold the TAB_PANEL role and be the target of the CONTROLS
+ *   relation with their corresponding tabs (in the stack
+ *   switcher or notebook).
+ */
+
 struct _GtkAtSpiContext
 {
   GtkATContext parent_instance;